<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width">
  <title>REPL | Node.js v8.12.0 Documentation</title>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic">
  <link rel="stylesheet" href="assets/style.css">
  <link rel="stylesheet" href="assets/sh.css">
  <link rel="canonical" href="https://nodejs.org/api/repl.html">
</head>
<body class="alt apidoc" id="api-section-repl">
  <div id="content" class="clearfix">
    <div id="column2" class="interior">
      <div id="intro" class="interior">
        <a href="/" title="Go back to the home page">
          Node.js
        </a>
      </div>
      <ul>
<li><a class="nav-documentation" href="documentation.html">About these Docs</a></li>
<li><a class="nav-synopsis" href="synopsis.html">Usage &amp; Example</a></li>
</ul>
<div class="line"></div>

<ul>
<li><a class="nav-assert" href="assert.html">Assertion Testing</a></li>
<li><a class="nav-async_hooks" href="async_hooks.html">Async Hooks</a></li>
<li><a class="nav-buffer" href="buffer.html">Buffer</a></li>
<li><a class="nav-addons" href="addons.html">C++ Addons</a></li>
<li><a class="nav-n-api" href="n-api.html">C/C++ Addons - N-API</a></li>
<li><a class="nav-child_process" href="child_process.html">Child Processes</a></li>
<li><a class="nav-cluster" href="cluster.html">Cluster</a></li>
<li><a class="nav-cli" href="cli.html">Command Line Options</a></li>
<li><a class="nav-console" href="console.html">Console</a></li>
<li><a class="nav-crypto" href="crypto.html">Crypto</a></li>
<li><a class="nav-debugger" href="debugger.html">Debugger</a></li>
<li><a class="nav-deprecations" href="deprecations.html">Deprecated APIs</a></li>
<li><a class="nav-dns" href="dns.html">DNS</a></li>
<li><a class="nav-domain" href="domain.html">Domain</a></li>
<li><a class="nav-esm" href="esm.html">ECMAScript Modules</a></li>
<li><a class="nav-errors" href="errors.html">Errors</a></li>
<li><a class="nav-events" href="events.html">Events</a></li>
<li><a class="nav-fs" href="fs.html">File System</a></li>
<li><a class="nav-globals" href="globals.html">Globals</a></li>
<li><a class="nav-http" href="http.html">HTTP</a></li>
<li><a class="nav-http2" href="http2.html">HTTP/2</a></li>
<li><a class="nav-https" href="https.html">HTTPS</a></li>
<li><a class="nav-inspector" href="inspector.html">Inspector</a></li>
<li><a class="nav-intl" href="intl.html">Internationalization</a></li>
<li><a class="nav-modules" href="modules.html">Modules</a></li>
<li><a class="nav-net" href="net.html">Net</a></li>
<li><a class="nav-os" href="os.html">OS</a></li>
<li><a class="nav-path" href="path.html">Path</a></li>
<li><a class="nav-perf_hooks" href="perf_hooks.html">Performance Hooks</a></li>
<li><a class="nav-process" href="process.html">Process</a></li>
<li><a class="nav-punycode" href="punycode.html">Punycode</a></li>
<li><a class="nav-querystring" href="querystring.html">Query Strings</a></li>
<li><a class="nav-readline" href="readline.html">Readline</a></li>
<li><a class="nav-repl active" href="repl.html">REPL</a></li>
<li><a class="nav-stream" href="stream.html">Stream</a></li>
<li><a class="nav-string_decoder" href="string_decoder.html">String Decoder</a></li>
<li><a class="nav-timers" href="timers.html">Timers</a></li>
<li><a class="nav-tls" href="tls.html">TLS/SSL</a></li>
<li><a class="nav-tracing" href="tracing.html">Tracing</a></li>
<li><a class="nav-tty" href="tty.html">TTY</a></li>
<li><a class="nav-dgram" href="dgram.html">UDP/Datagram</a></li>
<li><a class="nav-url" href="url.html">URL</a></li>
<li><a class="nav-util" href="util.html">Utilities</a></li>
<li><a class="nav-v8" href="v8.html">V8</a></li>
<li><a class="nav-vm" href="vm.html">VM</a></li>
<li><a class="nav-zlib" href="zlib.html">ZLIB</a></li>
</ul>
<div class="line"></div>

<ul>
<li><a class="nav-https-github-com-nodejs-node" href="https://github.com/nodejs/node">GitHub Repo &amp; Issue Tracker</a></li>
<li><a class="nav-https-groups-google-com-group-nodejs" href="https://groups.google.com/group/nodejs">Mailing List</a></li>
</ul>

    </div>

    <div id="column1" data-id="repl" class="interior">
      <header>
        <h1>Node.js v8.12.0 Documentation</h1>
        <div id="gtoc">
          <ul>
            <li>
              <a href="index.html" name="toc">Index</a>
            </li>
            <li>
              <a href="all.html">View on single page</a>
            </li>
            <li>
              <a href="repl.json">View as JSON</a>
            </li>
            
    <li class="version-picker">
      <a href="#">View another version <span>&#x25bc;</span></a>
      <ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v9.x/api/repl.html">9.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v8.x/api/repl.html">8.x <b>LTS</b></a></li>
<li><a href="https://nodejs.org/docs/latest-v7.x/api/repl.html">7.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v6.x/api/repl.html">6.x <b>LTS</b></a></li>
<li><a href="https://nodejs.org/docs/latest-v5.x/api/repl.html">5.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v4.x/api/repl.html">4.x <b>LTS</b></a></li>
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/repl.html">0.12.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/repl.html">0.10.x</a></li></ol>
    </li>
  
          </ul>
        </div>
        <hr>
      </header>

      <div id="toc">
        <h2>Table of Contents</h2>
        <ul>
<li><span class="stability_2"><a href="#repl_repl">REPL</a></span><ul>
<li><span class="stability_undefined"><a href="#repl_design_and_features">Design and Features</a></span><ul>
<li><span class="stability_undefined"><a href="#repl_commands_and_special_keys">Commands and Special Keys</a></span></li>
<li><span class="stability_undefined"><a href="#repl_default_evaluation">Default Evaluation</a></span><ul>
<li><span class="stability_undefined"><a href="#repl_javascript_expressions">JavaScript Expressions</a></span></li>
<li><span class="stability_undefined"><a href="#repl_global_and_local_scope">Global and Local Scope</a></span></li>
<li><span class="stability_undefined"><a href="#repl_accessing_core_node_js_modules">Accessing Core Node.js Modules</a></span></li>
<li><span class="stability_undefined"><a href="#repl_assignment_of_the_underscore_variable">Assignment of the <code>_</code> (underscore) variable</a></span></li>
</ul>
</li>
<li><span class="stability_undefined"><a href="#repl_custom_evaluation_functions">Custom Evaluation Functions</a></span><ul>
<li><span class="stability_undefined"><a href="#repl_recoverable_errors">Recoverable Errors</a></span></li>
</ul>
</li>
<li><span class="stability_undefined"><a href="#repl_customizing_repl_output">Customizing REPL Output</a></span></li>
</ul>
</li>
<li><span class="stability_undefined"><a href="#repl_class_replserver">Class: REPLServer</a></span><ul>
<li><span class="stability_undefined"><a href="#repl_event_exit">Event: &#39;exit&#39;</a></span></li>
<li><span class="stability_undefined"><a href="#repl_event_reset">Event: &#39;reset&#39;</a></span></li>
<li><span class="stability_undefined"><a href="#repl_replserver_definecommand_keyword_cmd">replServer.defineCommand(keyword, cmd)</a></span></li>
<li><span class="stability_undefined"><a href="#repl_replserver_displayprompt_preservecursor">replServer.displayPrompt([preserveCursor])</a></span></li>
</ul>
</li>
<li><span class="stability_undefined"><a href="#repl_repl_start_options">repl.start([options])</a></span></li>
<li><span class="stability_undefined"><a href="#repl_the_node_js_repl">The Node.js REPL</a></span><ul>
<li><span class="stability_undefined"><a href="#repl_environment_variable_options">Environment Variable Options</a></span></li>
<li><span class="stability_undefined"><a href="#repl_persistent_history">Persistent History</a></span><ul>
<li><span class="stability_0"><a href="#repl_node_repl_history_file">NODE_REPL_HISTORY_FILE</a></span></li>
</ul>
</li>
<li><span class="stability_undefined"><a href="#repl_using_the_node_js_repl_with_advanced_line_editors">Using the Node.js REPL with advanced line-editors</a></span></li>
<li><span class="stability_undefined"><a href="#repl_starting_multiple_repl_instances_against_a_single_running_instance">Starting multiple REPL instances against a single running instance</a></span></li>
</ul>
</li>
</ul>
</li>
</ul>

      </div>

      <div id="apicontent">
        <h1>REPL<span><a class="mark" href="#repl_repl" id="repl_repl">#</a></span></h1>
<!--introduced_in=v0.10.0-->
<div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div><p>The <code>repl</code> module provides a Read-Eval-Print-Loop (REPL) implementation that
is available both as a standalone program or includible in other applications.
It can be accessed using:</p>
<pre><code class="lang-js">const repl = require(&#39;repl&#39;);
</code></pre>
<h2>Design and Features<span><a class="mark" href="#repl_design_and_features" id="repl_design_and_features">#</a></span></h2>
<p>The <code>repl</code> module exports the <code>repl.REPLServer</code> class. While running, instances
of <code>repl.REPLServer</code> will accept individual lines of user input, evaluate those
according to a user-defined evaluation function, then output the result. Input
and output may be from <code>stdin</code> and <code>stdout</code>, respectively, or may be connected
to any Node.js <a href="stream.html">stream</a>.</p>
<p>Instances of <code>repl.REPLServer</code> support automatic completion of inputs,
simplistic Emacs-style line editing, multi-line inputs, ANSI-styled output,
saving and restoring current REPL session state, error recovery, and
customizable evaluation functions.</p>
<h3>Commands and Special Keys<span><a class="mark" href="#repl_commands_and_special_keys" id="repl_commands_and_special_keys">#</a></span></h3>
<p>The following special commands are supported by all REPL instances:</p>
<ul>
<li><code>.break</code> - When in the process of inputting a multi-line expression, entering
the <code>.break</code> command (or pressing the <code>&lt;ctrl&gt;-C</code> key combination) will abort
further input or processing of that expression.</li>
<li><code>.clear</code> - Resets the REPL <code>context</code> to an empty object and clears any
multi-line expression currently being input.</li>
<li><code>.exit</code> - Close the I/O stream, causing the REPL to exit.</li>
<li><code>.help</code> - Show this list of special commands.</li>
<li><code>.save</code> - Save the current REPL session to a file:
<code>&gt; .save ./file/to/save.js</code></li>
<li><code>.load</code> - Load a file into the current REPL session.
<code>&gt; .load ./file/to/load.js</code></li>
<li><code>.editor</code> - Enter editor mode (<code>&lt;ctrl&gt;-D</code> to finish, <code>&lt;ctrl&gt;-C</code> to cancel)</li>
</ul>
<!-- eslint-skip -->
<pre><code class="lang-js">&gt; .editor
// Entering editor mode (^D to finish, ^C to cancel)
function welcome(name) {
  return `Hello ${name}!`;
}

welcome(&#39;Node.js User&#39;);

// ^D
&#39;Hello Node.js User!&#39;
&gt;
</code></pre>
<p>The following key combinations in the REPL have these special effects:</p>
<ul>
<li><code>&lt;ctrl&gt;-C</code> - When pressed once, has the same effect as the <code>.break</code> command.
When pressed twice on a blank line, has the same effect as the <code>.exit</code>
command.</li>
<li><code>&lt;ctrl&gt;-D</code> - Has the same effect as the <code>.exit</code> command.</li>
<li><code>&lt;tab&gt;</code> - When pressed on a blank line, displays global and local(scope)
variables. When pressed while entering other input, displays relevant
autocompletion options.</li>
</ul>
<h3>Default Evaluation<span><a class="mark" href="#repl_default_evaluation" id="repl_default_evaluation">#</a></span></h3>
<p>By default, all instances of <code>repl.REPLServer</code> use an evaluation function that
evaluates JavaScript expressions and provides access to Node.js&#39; built-in
modules. This default behavior can be overridden by passing in an alternative
evaluation function when the <code>repl.REPLServer</code> instance is created.</p>
<h4>JavaScript Expressions<span><a class="mark" href="#repl_javascript_expressions" id="repl_javascript_expressions">#</a></span></h4>
<p>The default evaluator supports direct evaluation of JavaScript expressions:</p>
<!-- eslint-skip -->
<pre><code class="lang-js">&gt; 1 + 1
2
&gt; const m = 2
undefined
&gt; m + 1
3
</code></pre>
<p>Unless otherwise scoped within blocks or functions, variables declared
either implicitly or using the <code>const</code>, <code>let</code>, or <code>var</code> keywords
are declared at the global scope.</p>
<h4>Global and Local Scope<span><a class="mark" href="#repl_global_and_local_scope" id="repl_global_and_local_scope">#</a></span></h4>
<p>The default evaluator provides access to any variables that exist in the global
scope. It is possible to expose a variable to the REPL explicitly by assigning
it to the <code>context</code> object associated with each <code>REPLServer</code>. For example:</p>
<pre><code class="lang-js">const repl = require(&#39;repl&#39;);
const msg = &#39;message&#39;;

repl.start(&#39;&gt; &#39;).context.m = msg;
</code></pre>
<p>Properties in the <code>context</code> object appear as local within the REPL:</p>
<!-- eslint-skip -->
<pre><code class="lang-js">$ node repl_test.js
&gt; m
&#39;message&#39;
</code></pre>
<p>Context properties are not read-only by default. To specify read-only globals,
context properties must be defined using <code>Object.defineProperty()</code>:</p>
<pre><code class="lang-js">const repl = require(&#39;repl&#39;);
const msg = &#39;message&#39;;

const r = repl.start(&#39;&gt; &#39;);
Object.defineProperty(r.context, &#39;m&#39;, {
  configurable: false,
  enumerable: true,
  value: msg
});
</code></pre>
<h4>Accessing Core Node.js Modules<span><a class="mark" href="#repl_accessing_core_node_js_modules" id="repl_accessing_core_node_js_modules">#</a></span></h4>
<p>The default evaluator will automatically load Node.js core modules into the
REPL environment when used. For instance, unless otherwise declared as a
global or scoped variable, the input <code>fs</code> will be evaluated on-demand as
<code>global.fs = require(&#39;fs&#39;)</code>.</p>
<!-- eslint-skip -->
<pre><code class="lang-js">&gt; fs.createReadStream(&#39;./some/file&#39;);
</code></pre>
<h4>Assignment of the <code>_</code> (underscore) variable<span><a class="mark" href="#repl_assignment_of_the_underscore_variable" id="repl_assignment_of_the_underscore_variable">#</a></span></h4>
<p>The default evaluator will, by default, assign the result of the most recently
evaluated expression to the special variable <code>_</code> (underscore).
Explicitly setting <code>_</code> to a value will disable this behavior.</p>
<!-- eslint-skip -->
<pre><code class="lang-js">&gt; [ &#39;a&#39;, &#39;b&#39;, &#39;c&#39; ]
[ &#39;a&#39;, &#39;b&#39;, &#39;c&#39; ]
&gt; _.length
3
&gt; _ += 1
Expression assignment to _ now disabled.
4
&gt; 1 + 1
2
&gt; _
4
</code></pre>
<h3>Custom Evaluation Functions<span><a class="mark" href="#repl_custom_evaluation_functions" id="repl_custom_evaluation_functions">#</a></span></h3>
<p>When a new <code>repl.REPLServer</code> is created, a custom evaluation function may be
provided. This can be used, for instance, to implement fully customized REPL
applications.</p>
<p>The following illustrates a hypothetical example of a REPL that performs
translation of text from one language to another:</p>
<pre><code class="lang-js">const repl = require(&#39;repl&#39;);
const { Translator } = require(&#39;translator&#39;);

const myTranslator = new Translator(&#39;en&#39;, &#39;fr&#39;);

function myEval(cmd, context, filename, callback) {
  callback(null, myTranslator.translate(cmd));
}

repl.start({ prompt: &#39;&gt; &#39;, eval: myEval });
</code></pre>
<h4>Recoverable Errors<span><a class="mark" href="#repl_recoverable_errors" id="repl_recoverable_errors">#</a></span></h4>
<p>As a user is typing input into the REPL prompt, pressing the <code>&lt;enter&gt;</code> key will
send the current line of input to the <code>eval</code> function. In order to support
multi-line input, the eval function can return an instance of <code>repl.Recoverable</code>
to the provided callback function:</p>
<pre><code class="lang-js">function myEval(cmd, context, filename, callback) {
  let result;
  try {
    result = vm.runInThisContext(cmd);
  } catch (e) {
    if (isRecoverableError(e)) {
      return callback(new repl.Recoverable(e));
    }
  }
  callback(null, result);
}

function isRecoverableError(error) {
  if (error.name === &#39;SyntaxError&#39;) {
    return /^(Unexpected end of input|Unexpected token)/.test(error.message);
  }
  return false;
}
</code></pre>
<h3>Customizing REPL Output<span><a class="mark" href="#repl_customizing_repl_output" id="repl_customizing_repl_output">#</a></span></h3>
<p>By default, <code>repl.REPLServer</code> instances format output using the
<a href="util.html#util_util_inspect_object_options"><code>util.inspect()</code></a> method before writing the output to the provided Writable
stream (<code>process.stdout</code> by default). The <code>useColors</code> boolean option can be
specified at construction to instruct the default writer to use ANSI style
codes to colorize the output from the <code>util.inspect()</code> method.</p>
<p>It is possible to fully customize the output of a <code>repl.REPLServer</code> instance
by passing a new function in using the <code>writer</code> option on construction. The
following example, for instance, simply converts any input text to upper case:</p>
<pre><code class="lang-js">const repl = require(&#39;repl&#39;);

const r = repl.start({ prompt: &#39;&gt; &#39;, eval: myEval, writer: myWriter });

function myEval(cmd, context, filename, callback) {
  callback(null, cmd);
}

function myWriter(output) {
  return output.toUpperCase();
}
</code></pre>
<h2>Class: REPLServer<span><a class="mark" href="#repl_class_replserver" id="repl_class_replserver">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.1.91</span>
</div><p>The <code>repl.REPLServer</code> class inherits from the <a href="readline.html#readline_class_interface"><code>readline.Interface</code></a> class.
Instances of <code>repl.REPLServer</code> are created using the <code>repl.start()</code> method and
<em>should not</em> be created directly using the JavaScript <code>new</code> keyword.</p>
<h3>Event: &#39;exit&#39;<span><a class="mark" href="#repl_event_exit" id="repl_event_exit">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.7.7</span>
</div><p>The <code>&#39;exit&#39;</code> event is emitted when the REPL is exited either by receiving the
<code>.exit</code> command as input, the user pressing <code>&lt;ctrl&gt;-C</code> twice to signal <code>SIGINT</code>,
or by pressing <code>&lt;ctrl&gt;-D</code> to signal <code>&#39;end&#39;</code> on the input stream. The listener
callback is invoked without any arguments.</p>
<pre><code class="lang-js">replServer.on(&#39;exit&#39;, () =&gt; {
  console.log(&#39;Received &quot;exit&quot; event from repl!&#39;);
  process.exit();
});
</code></pre>
<h3>Event: &#39;reset&#39;<span><a class="mark" href="#repl_event_reset" id="repl_event_reset">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.11.0</span>
</div><p>The <code>&#39;reset&#39;</code> event is emitted when the REPL&#39;s context is reset. This occurs
whenever the <code>.clear</code> command is received as input <em>unless</em> the REPL is using
the default evaluator and the <code>repl.REPLServer</code> instance was created with the
<code>useGlobal</code> option set to <code>true</code>. The listener callback will be called with a
reference to the <code>context</code> object as the only argument.</p>
<p>This can be used primarily to re-initialize REPL context to some pre-defined
state as illustrated in the following simple example:</p>
<pre><code class="lang-js">const repl = require(&#39;repl&#39;);

function initializeContext(context) {
  context.m = &#39;test&#39;;
}

const r = repl.start({ prompt: &#39;&gt; &#39; });
initializeContext(r.context);

r.on(&#39;reset&#39;, initializeContext);
</code></pre>
<p>When this code is executed, the global <code>&#39;m&#39;</code> variable can be modified but then
reset to its initial value using the <code>.clear</code> command:</p>
<!-- eslint-skip -->
<pre><code class="lang-js">$ ./node example.js
&gt; m
&#39;test&#39;
&gt; m = 1
1
&gt; m
1
&gt; .clear
Clearing context...
&gt; m
&#39;test&#39;
&gt;
</code></pre>
<h3>replServer.defineCommand(keyword, cmd)<span><a class="mark" href="#repl_replserver_definecommand_keyword_cmd" id="repl_replserver_definecommand_keyword_cmd">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.3.0</span>
</div><ul>
<li><code>keyword</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> The command keyword (<em>without</em> a leading <code>.</code> character).</li>
<li><code>cmd</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type">&lt;Object&gt;</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> The function to invoke when the command is processed.</li>
</ul>
<p>The <code>replServer.defineCommand()</code> method is used to add new <code>.</code>-prefixed commands
to the REPL instance. Such commands are invoked by typing a <code>.</code> followed by the
<code>keyword</code>. The <code>cmd</code> is either a Function or an object with the following
properties:</p>
<ul>
<li><code>help</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> Help text to be displayed when <code>.help</code> is entered (Optional).</li>
<li><code>action</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> The function to execute, optionally accepting a single
string argument.</li>
</ul>
<p>The following example shows two new commands added to the REPL instance:</p>
<pre><code class="lang-js">const repl = require(&#39;repl&#39;);

const replServer = repl.start({ prompt: &#39;&gt; &#39; });
replServer.defineCommand(&#39;sayhello&#39;, {
  help: &#39;Say hello&#39;,
  action(name) {
    this.bufferedCommand = &#39;&#39;;
    console.log(`Hello, ${name}!`);
    this.displayPrompt();
  }
});
replServer.defineCommand(&#39;saybye&#39;, function saybye() {
  console.log(&#39;Goodbye!&#39;);
  this.close();
});
</code></pre>
<p>The new commands can then be used from within the REPL instance:</p>
<pre><code class="lang-txt">&gt; .sayhello Node.js User
Hello, Node.js User!
&gt; .saybye
Goodbye!
</code></pre>
<h3>replServer.displayPrompt([preserveCursor])<span><a class="mark" href="#repl_replserver_displayprompt_preservecursor" id="repl_replserver_displayprompt_preservecursor">#</a></span></h3>
<div class="api_metadata">
<span>Added in: v0.1.91</span>
</div><ul>
<li><code>preserveCursor</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&lt;boolean&gt;</a></li>
</ul>
<p>The <code>replServer.displayPrompt()</code> method readies the REPL instance for input
from the user, printing the configured <code>prompt</code> to a new line in the <code>output</code>
and resuming the <code>input</code> to accept new input.</p>
<p>When multi-line input is being entered, an ellipsis is printed rather than the
&#39;prompt&#39;.</p>
<p>When <code>preserveCursor</code> is <code>true</code>, the cursor placement will not be reset to <code>0</code>.</p>
<p>The <code>replServer.displayPrompt</code> method is primarily intended to be called from
within the action function for commands registered using the
<code>replServer.defineCommand()</code> method.</p>
<h2>repl.start([options])<span><a class="mark" href="#repl_repl_start_options" id="repl_repl_start_options">#</a></span></h2>
<div class="api_metadata">
<details class="changelog"><summary>History</summary>
<table>
<tr><th>Version</th><th>Changes</th></tr>
<tr><td>v5.8.0</td>
<td><p>The <code>options</code> parameter is optional now.</p>
</td></tr>
<tr><td>v0.1.91</td>
<td><p><span>Added in: v0.1.91</span></p>
</td></tr>
</table>
</details>
</div><ul>
<li><code>options</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type">&lt;Object&gt;</a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a><ul>
<li><code>prompt</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type">&lt;string&gt;</a> The input prompt to display. <strong>Default:</strong> <code>&gt;</code>.
(with a trailing space).</li>
<li><code>input</code> <a href="stream.html#stream_class_stream_readable" class="type">&lt;stream.Readable&gt;</a> The Readable stream from which REPL input will be
read. <strong>Default:</strong> <code>process.stdin</code>.</li>
<li><code>output</code> <a href="stream.html#stream_class_stream_writable" class="type">&lt;stream.Writable&gt;</a> The Writable stream to which REPL output will be
written. <strong>Default:</strong> <code>process.stdout</code>.</li>
<li><code>terminal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&lt;boolean&gt;</a> If <code>true</code>, specifies that the <code>output</code> should be
treated as a TTY terminal, and have ANSI/VT100 escape codes written to it.
<strong>Default:</strong> checking the value of the <code>isTTY</code> property on the <code>output</code>
stream upon instantiation.</li>
<li><code>eval</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> The function to be used when evaluating each given line
of input. <strong>Default:</strong> an async wrapper for the JavaScript <code>eval()</code>
function. An <code>eval</code> function can error with <code>repl.Recoverable</code> to indicate
the input was incomplete and prompt for additional lines.</li>
<li><code>useColors</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&lt;boolean&gt;</a> If <code>true</code>, specifies that the default <code>writer</code>
function should include ANSI color styling to REPL output. If a custom
<code>writer</code> function is provided then this has no effect. <strong>Default:</strong> the
 REPL instances <code>terminal</code> value.</li>
<li><code>useGlobal</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&lt;boolean&gt;</a> If <code>true</code>, specifies that the default evaluation
 function will use the JavaScript <code>global</code> as the context as opposed to
 creating a new separate context for the REPL instance. The node CLI REPL
 sets this value to <code>true</code>. <strong>Default:</strong> <code>false</code>.</li>
<li><code>ignoreUndefined</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type" class="type">&lt;boolean&gt;</a> If <code>true</code>, specifies that the default writer
 will not output the return value of a command if it evaluates to
 <code>undefined</code>. <strong>Default:</strong> <code>false</code>.</li>
<li><code>writer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> The function to invoke to format the output of each
 command before writing to <code>output</code>. <strong>Default:</strong> <a href="util.html#util_util_inspect_object_options"><code>util.inspect()</code></a>.</li>
<li><code>completer</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function" class="type">&lt;Function&gt;</a> An optional function used for custom Tab auto
 completion. See <a href="readline.html#readline_use_of_the_completer_function"><code>readline.InterfaceCompleter</code></a> for an example.</li>
<li><code>replMode</code> <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Symbol_type" class="type">&lt;symbol&gt;</a> A flag that specifies whether the default evaluator
executes all JavaScript commands in strict mode or default (sloppy) mode.
Acceptable values are:<ul>
<li><code>repl.REPL_MODE_SLOPPY</code> - evaluates expressions in sloppy mode.</li>
<li><code>repl.REPL_MODE_STRICT</code> - evaluates expressions in strict mode. This is
equivalent to prefacing every repl statement with <code>&#39;use strict&#39;</code>.</li>
<li><code>repl.REPL_MODE_MAGIC</code> - This value is <strong>deprecated</strong>, since enhanced
spec compliance in V8 has rendered magic mode unnecessary. It is now
equivalent to <code>repl.REPL_MODE_SLOPPY</code> (documented above).</li>
</ul>
</li>
<li><code>breakEvalOnSigint</code> - Stop evaluating the current piece of code when
<code>SIGINT</code> is received, i.e. <code>Ctrl+C</code> is pressed. This cannot be used together
with a custom <code>eval</code> function. <strong>Default:</strong> <code>false</code>.</li>
</ul>
</li>
</ul>
<p>The <code>repl.start()</code> method creates and starts a <code>repl.REPLServer</code> instance.</p>
<p>If <code>options</code> is a string, then it specifies the input prompt:</p>
<pre><code class="lang-js">const repl = require(&#39;repl&#39;);

// a Unix style prompt
repl.start(&#39;$ &#39;);
</code></pre>
<h2>The Node.js REPL<span><a class="mark" href="#repl_the_node_js_repl" id="repl_the_node_js_repl">#</a></span></h2>
<p>Node.js itself uses the <code>repl</code> module to provide its own interactive interface
for executing JavaScript. This can be used by executing the Node.js binary
without passing any arguments (or by passing the <code>-i</code> argument):</p>
<!-- eslint-skip -->
<pre><code class="lang-js">$ node
&gt; const a = [1, 2, 3];
undefined
&gt; a
[ 1, 2, 3 ]
&gt; a.forEach((v) =&gt; {
...   console.log(v);
...   });
1
2
3
</code></pre>
<h3>Environment Variable Options<span><a class="mark" href="#repl_environment_variable_options" id="repl_environment_variable_options">#</a></span></h3>
<p>Various behaviors of the Node.js REPL can be customized using the following
environment variables:</p>
<ul>
<li><code>NODE_REPL_HISTORY</code> - When a valid path is given, persistent REPL history
will be saved to the specified file rather than <code>.node_repl_history</code> in the
user&#39;s home directory. Setting this value to <code>&#39;&#39;</code> will disable persistent
REPL history. Whitespace will be trimmed from the value.</li>
<li><code>NODE_REPL_HISTORY_SIZE</code> - Controls how many lines of history will be
persisted if history is available. Must be a positive number.
<strong>Default:</strong> <code>1000</code>.</li>
<li><code>NODE_REPL_MODE</code> - May be any of <code>sloppy</code>, <code>strict</code>, or <code>magic</code>. <code>magic</code> is
<strong>deprecated</strong> and treated as an alias of <code>sloppy</code>. <strong>Default:</strong> <code>sloppy</code>,
which will allow non-strict mode code to be run.</li>
</ul>
<h3>Persistent History<span><a class="mark" href="#repl_persistent_history" id="repl_persistent_history">#</a></span></h3>
<p>By default, the Node.js REPL will persist history between <code>node</code> REPL sessions
by saving inputs to a <code>.node_repl_history</code> file located in the user&#39;s home
directory. This can be disabled by setting the environment variable
<code>NODE_REPL_HISTORY=&quot;&quot;</code>.</p>
<h4>NODE_REPL_HISTORY_FILE<span><a class="mark" href="#repl_node_repl_history_file" id="repl_node_repl_history_file">#</a></span></h4>
<div class="api_metadata">
<span>Added in: v2.0.0</span><span>Deprecated since: v3.0.0</span>
</div><div class="api_stability api_stability_0"><a href="documentation.html#documentation_stability_index">Stability: 0</a> - Deprecated: Use <code>NODE_REPL_HISTORY</code> instead.</div><p>Previously in Node.js/io.js v2.x, REPL history was controlled by using a
<code>NODE_REPL_HISTORY_FILE</code> environment variable, and the history was saved in JSON
format. This variable has now been deprecated, and the old JSON REPL history
file will be automatically converted to a simplified plain text format. This new
file will be saved to either the user&#39;s home directory, or a directory defined
by the <code>NODE_REPL_HISTORY</code> variable, as documented in the
<a href="#repl_environment_variable_options">Environment Variable Options</a>.</p>
<h3>Using the Node.js REPL with advanced line-editors<span><a class="mark" href="#repl_using_the_node_js_repl_with_advanced_line_editors" id="repl_using_the_node_js_repl_with_advanced_line_editors">#</a></span></h3>
<p>For advanced line-editors, start Node.js with the environment variable
<code>NODE_NO_READLINE=1</code>. This will start the main and debugger REPL in canonical
terminal settings, which will allow use with <code>rlwrap</code>.</p>
<p>For example, the following can be added to a <code>.bashrc</code> file:</p>
<pre><code class="lang-text">alias node=&quot;env NODE_NO_READLINE=1 rlwrap node&quot;
</code></pre>
<h3>Starting multiple REPL instances against a single running instance<span><a class="mark" href="#repl_starting_multiple_repl_instances_against_a_single_running_instance" id="repl_starting_multiple_repl_instances_against_a_single_running_instance">#</a></span></h3>
<p>It is possible to create and run multiple REPL instances against a single
running instance of Node.js that share a single <code>global</code> object but have
separate I/O interfaces.</p>
<p>The following example, for instance, provides separate REPLs on <code>stdin</code>, a Unix
socket, and a TCP socket:</p>
<pre><code class="lang-js">const net = require(&#39;net&#39;);
const repl = require(&#39;repl&#39;);
let connections = 0;

repl.start({
  prompt: &#39;Node.js via stdin&gt; &#39;,
  input: process.stdin,
  output: process.stdout
});

net.createServer((socket) =&gt; {
  connections += 1;
  repl.start({
    prompt: &#39;Node.js via Unix socket&gt; &#39;,
    input: socket,
    output: socket
  }).on(&#39;exit&#39;, () =&gt; {
    socket.end();
  });
}).listen(&#39;/tmp/node-repl-sock&#39;);

net.createServer((socket) =&gt; {
  connections += 1;
  repl.start({
    prompt: &#39;Node.js via TCP socket&gt; &#39;,
    input: socket,
    output: socket
  }).on(&#39;exit&#39;, () =&gt; {
    socket.end();
  });
}).listen(5001);
</code></pre>
<p>Running this application from the command line will start a REPL on stdin.
Other REPL clients may connect through the Unix socket or TCP socket. <code>telnet</code>,
for instance, is useful for connecting to TCP sockets, while <code>socat</code> can be used
to connect to both Unix and TCP sockets.</p>
<p>By starting a REPL from a Unix socket-based server instead of stdin, it is
possible to connect to a long-running Node.js process without restarting it.</p>
<p>For an example of running a &quot;full-featured&quot; (<code>terminal</code>) REPL over
a <code>net.Server</code> and <code>net.Socket</code> instance, see: <a href="https://gist.github.com/2209310">https://gist.github.com/2209310</a></p>
<p>For an example of running a REPL instance over <a href="https://curl.haxx.se/docs/manpage.html">curl(1)</a>,
see: <a href="https://gist.github.com/2053342">https://gist.github.com/2053342</a></p>

      </div>
    </div>
  </div>
  <script src="assets/sh_main.js"></script>
  <script src="assets/sh_javascript.min.js"></script>
  <script>highlight(undefined, undefined, 'pre');</script>
  <!-- __TRACKING__ -->
</body>
</html>

